<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>The AspectJtm Problem Diagnosis Guide</title><link rel="stylesheet" href="aspectj-docs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.44"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" id="d0e1"><div class="titlepage"><div><h1 class="title"><a name="d0e1"></a>The AspectJ<sup>tm</sup> Problem Diagnosis Guide</h1></div><div><h3 class="author">the AspectJ Team</h3></div><div><div class="legalnotice"><p>Copyright (c) 2006 IBM Corporation and others.
         2006 Contributors.  
         All rights reserved.
        </p></div></div><div><div class="abstract"><p><a name="d0e15"></a><b>Abstract</b></p><p>
          This guide describes how to configure the AspectJ compiler/weaver to provide
          information for diagnosing problems in the input programs, the 
          compiler/weaver or its configuration.
      </p><p>
          The AspectJ compiler and weaver can provide lots of information for diagnosing
          problems in building AspectJ programs.  For problems in the input program,
          there are a number of default warning and error messages, as well as many 
          configurable "lint" messages, all of which can be emitted normally, 
          logged using standard facilities, or intercepted programmatically. 
          These are discussed in <a href="#messages">Messages</a>.  Since most errors
          relate to writing pointcuts incorrectly, there is a section on 
          <a href="#pointcuts">Debugging Pointcuts</a>.
      </p><p>
          For problems with the compiler/weaver itself there are three facilities
          that enable the AspectJ developers to resolve bugs even when it is
          too hard to deliver a reproducible test case: 
        <div class="orderedlist"><ol type="1"><li><p><a name="d0e27"></a><a href="#trace">Tracing</a> can be enabled to track progress up to the time of a failure;</p></li><li><p><a name="d0e31"></a><a href="#ajcore">AspectJ Core Files</a> can give a relatively complete picture of the state of 
          the world at the time of a failure; and </p></li><li><p><a name="d0e35"></a><a href="#ltwdump">Dumping classes during load-time weaving</a> is a way to capture both 
                input and output classes during load-time weaving.
          </p></li></ol></div>
          </p><p>
          This guide describes how to configure messages to get the right information
          and how to configure traces, dumps, and core files.  Although the compiler/weaver
          operates in roughly three modes (from the command-line, embedded in an IDE, 
          and enabled as load-time weaving), the principles are basically the same for 
          all modes.  The differences lie in how to set up diagnostics and what 
          information is likely to be relevant.   
      </p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>1. <a href="#messages">Messages</a></dt><dd><dl><dt><a href="#messages-introduction">Introduction</a></dt><dd><dl><dt><a href="#messages-introduction-config">Configuring Messages</a></dt></dl></dd><dt><a href="#messages-scenarios">Message scenarios</a></dt><dd><dl><dt><a href="#messages-scenarios-ct">Compile-time weaving scenarios</a></dt><dt><a href="#messages-scenarios-ltw">Load-time weaving scenarios</a></dt></dl></dd><dt><a href="#messages-xlint">Lint messages</a></dt></dl></dd><dt>2. <a href="#pointcuts">Debugging Pointcuts</a></dt><dd><dl><dt><a href="#pointcuts-introduction">Introduction</a></dt><dt><a href="#pointcuts-debugging">Debugging pointcuts</a></dt></dl></dd><dt>3. <a href="#ajcore">AspectJ Core Files</a></dt><dd><dl><dt><a href="#ajcore-introduction">Introduction</a></dt><dd><dl><dt><a href="#configuration">Configuring dump files</a></dt><dt><a href="#ajcore-examples">AJCore File Examples</a></dt></dl></dd></dl></dd><dt>4. <a href="#trace">Tracing</a></dt><dd><dl><dt><a href="#trace-introduction">Introduction</a></dt><dd><dl><dt><a href="#trace-configuration">Configuring Tracing</a></dt><dt><a href="#trace-examples">Examples</a></dt></dl></dd></dl></dd><dt>5. <a href="#ltwdump">Dumping classes during load-time weaving</a></dt><dd><dl><dt><a href="#ltwdump-introduction">Introduction</a></dt><dd><dl><dt><a href="#ltw-examples">Configuring bytecode dumping in load-time weaving</a></dt><dt><a href="#ltwdump-examples">LTW Dump Examples</a></dt></dl></dd></dl></dd></dl></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="messages"></a>Chapter 1. Messages</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#messages-introduction">Introduction</a></dt><dd><dl><dt><a href="#messages-introduction-config">Configuring Messages</a></dt></dl></dd><dt><a href="#messages-scenarios">Message scenarios</a></dt><dd><dl><dt><a href="#messages-scenarios-ct">Compile-time weaving scenarios</a></dt><dt><a href="#messages-scenarios-ltw">Load-time weaving scenarios</a></dt></dl></dd><dt><a href="#messages-xlint">Lint messages</a></dt></dl></div><div class="sect1"><a name="messages-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="messages-introduction"></a>Introduction</h2></div></div><p>
            Messages point out potential problems in the input program; some
            are clearly problems (errors), but many more may depend on what
            the programmer intends.  To keep the noise down the latter are treated
            as warnings which can be ignored by the programmer or information
            which are hidden. However, when investigating
            unexpected behavior it's helpful to show them.  This section describes how
            to configure messages, presents some problem scenarios when
            compiling or doing load-time weaving, and summarizes some of the 
            more relevant messages.
        </p><div class="sect2"><a name="messages-introduction-config"></a><div class="titlepage"><div><h3 class="title"><a name="messages-introduction-config"></a>Configuring Messages</h3></div></div><p>
                The compiler offers <tt>-verbose</tt>, 
                <tt>-warning</tt>, and <tt>-XLint</tt> options 
                when invoked using the command-line, Ant, or embedded in an IDE.  
                All options are listed in the AspectJ Development Environment Guide 
                sections for 
                <a href="../devguide/ajc-ref.html" target="_top">Ajc</a> and 
                <a href="../devguide/antTasks-iajc.html" target="_top">Ant Tasks</a>.
                The <a href="../devguide/ltw.html" target="_top">Load-time Weaving</a> 
                section describes how to use XML configuration files and
                system properties to pass options to the weaver.  (You can also
                pass options to the weaver using system properties in build-
                time weaving.) 
                The <tt>-verbose</tt> option has the effect of including
                messages level "info", which are normally ignored.
                Both <tt>warning</tt> and <tt>XLint</tt>
                enable you to identify specific messages to emit, but warning 
                messages tend to be the same provided by the underlying Eclipse 
                JDT (Java) compiler, while XLint messages are emitted by the 
                AspectJ compiler or weaver.  Obviously, during load-time weaving
                only weaver messages will be emitted.  Similarly, if aspects
                are compiled but not woven, then only compiler messages will be
                emitted.  However, the usual case for the compiler/weaver working
                at build time is to emit both compiler and weaver messages.
            </p><p> The tables below list some options, System Properties (for LTW only) and Java 5 annotations 
            used to control AspectJ messages. The method
            of configuration depends on your environment so please refer to the relevant 
            documentation for 
            <a href="../devguide/ajc-ref.html" target="_top">ajc</a>, 
            <a href="../devguide/antTasks.html" target="_top">Ant</a> or 
            <a href="../devguide/ltw-configuration.html#weaver-options" target="_top">LTW</a>. 
            </p><p>
            <div class="informaltable" id="d0e95"><a name="d0e95"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td><tt>-verbose</tt></td><td>
                            	Show informational messages including AspectJ version
                            	and build date.
                            </td></tr><tr><td><tt>-debug</tt></td><td>
                            	(Load-time weaving only). Show debugging messages such as
                            	which classes are being woven or those that are excluded.
                                (This is not related to the compiler -g option to
                                include debug information in the output .class files.)
                            </td></tr><tr><td><tt>-showWeaveInfo</tt></td><td>
                            	Show weaving messages.
                            </td></tr><tr><td><tt>-Xlint</tt></td><td>
                            	Control level of lint messages.
                            </td></tr><tr><td><tt>messageHolderClass</tt>/
                                <tt>-XmessageHolderClass:</tt></td><td>
                            	In Ant tasks and LTW respectively specify the class to receive all messages.
                                See 
                                <a href="../devguide/antTasks-iajc.html#antTasks-iajc-options" target="_top">
                                iajc task options</a> or
                                <a href="../devguide/ltw-configuration.html#weaver-options" target="_top">
                                Weaver Options</a>.
                            </td></tr></tbody></table></div>
			</p><p>
            <div class="informaltable" id="d0e147"><a name="d0e147"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>System Property</th><th>Description</th></tr></thead><tbody><tr><td><tt>aj.weaving.verbose</tt></td><td>
                            	 Show informational messages including AspectJ version and build date 
                            	 (same as <tt>-verbose</tt> option).
                            </td></tr><tr><td><tt>org.aspectj.weaver.showWeaveInfo</tt></td><td>
                            	Show weaving messages
                            	(same as <tt>-showWeaveInfo</tt> option).
                            </td></tr><tr><td><tt>org.aspectj.weaving.messages</tt></td><td>
                            	Set this system property to enable tracing of all compiler 
                            	messages. See <a href="#trace-configuration">Configuring Tracing</a>.
                            </td></tr></tbody></table></div>
            </p><p>
            <div class="informaltable" id="d0e185"><a name="d0e185"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Annotation</th><th>Description</th></tr></thead><tbody><tr><td><tt>@SuppressAjWarnings</tt></td><td>
                            	Include this is Java 5 code to suppress AspectJ
                                warnings associated with the next line of code.
                            </td></tr></tbody></table></div>
            </p></div></div><div class="sect1"><a name="messages-scenarios"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="messages-scenarios"></a>Message scenarios</h2></div></div><div class="sect2"><a name="messages-scenarios-ct"></a><div class="titlepage"><div><h3 class="title"><a name="messages-scenarios-ct"></a>Compile-time weaving scenarios</h3></div></div><div class="sect3"><a name="messages-scenarios-ct-adviceNotWoven"></a><div class="titlepage"><div><h4 class="title"><a name="messages-scenarios-ct-adviceNotWoven"></a>Advice not woven</h4></div></div><p>This means that the pointcut for the advice did not match,
                and it should be debugged as described in 
                    <a href="#pointcuts">Debugging Pointcuts</a>.</p></div></div><div class="sect2"><a name="messages-scenarios-ltw"></a><div class="titlepage"><div><h3 class="title"><a name="messages-scenarios-ltw"></a>Load-time weaving scenarios</h3></div></div><p> You can use <tt>META-INF/aop.xml</tt> to control which
            messages are produced during LTW. The following example will produce
            basic informational messages about the lifecyle of the weaver in
            addition to any warning or error messages. </p><pre class="programlisting">
	&lt;aspectj&gt;
		&lt;weaver options="-verbose"&gt;
		&lt;/weaver&gt;
	&lt;/aspectj&gt;
			</pre><p>The messages indicate which <tt>META-INF/aop.xml</tt> 
            configurations file(s) are being used. Each message is also preceeded by the 
            name of the defining class loader associated with weaver. You can use this
            information in a large system to distinguish between different applications each
            of which will typically have its own class loader. </p><pre class="programlisting">
[AppClassLoader@92e78c] info AspectJ Weaver Version 1.5.3 built on Thursday Oct 26, 2006 at 17:22:31 GMT
[AppClassLoader@92e78c] info register classloader sun.misc.Launcher$AppClassLoader@92e78c
[AppClassLoader@92e78c] info using configuration /C:/temp/META-INF/aop.xml
[AppClassLoader@92e78c] info using configuration /C:/temp/META-INF/aop-ajc.xml
[AppClassLoader@92e78c] info register aspect ExceptionHandler
[AppClassLoader@92e78c] info processing reweavable type ExceptionHandler: ExceptionHandler.aj
			</pre><div class="sect3"><a name="messages-scenarios-ltw-adviceNotWoven"></a><div class="titlepage"><div><h4 class="title"><a name="messages-scenarios-ltw-adviceNotWoven"></a>Advice not woven</h4></div></div><p> It is often difficult to determine, especially when using load-time weaving (LTW),
		why advice has not been woven. Here is a quick guide to the messages to
		look for. Firstly if you use the <tt>-verbose</tt> option you 
		should see the following message when your aspect is registered: </p><pre class="programlisting">
	info register aspect MyAspect
        </pre><p> Secondly if you use the <tt>-debug</tt> option you should 
		see a message indicating that you class is being woven: </p><pre class="programlisting">
	debug weaving 'HelloWorld'
        </pre><p> However this does not mean that advice has actually been woven into
		your class; it says that the class has been passed to the weaver. To determine
		whether your pointcuts match you can use the <tt>-showWeaveInfo</tt>
		option which will cause a message to be issued each time a join point is woven: </p><pre class="programlisting">
	weaveinfo Join point 'method-execution(void HelloWorld.main(java.lang.String[]))' ...
		</pre><p>If advice is woven at this join point you should get the 
            corresponding message.</p></div></div></div><div class="sect1"><a name="messages-xlint"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="messages-xlint"></a>Lint messages</h2></div></div><p> 
                The table below lists some useful <tt>-Xlint</tt> messages. </p><div class="informaltable" id="d0e265"><a name="d0e265"></a><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Message</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><tt>aspectExcludedByConfiguration</tt></td><td><tt>ignore</tt></td><td>
                            	If an aspect is not being woven, despite being
                            	registered, it could be that it has been excluded
                            	by either an <tt>include</tt> or <tt>exclude</tt> 
                            	element in the 
                            	<tt>aspects</tt> section of <tt>META-INF/aop.xml</tt>.
                            	Enable this message to determine whether an aspect has
                            	been excluded.
                            </td></tr><tr><td><tt>adviceDidNotMatch</tt></td><td><tt>warning</tt></td><td>
                            	Issued when advice did not potentially affect any join points.
                                This means the corresponding pointcut did not match any join
                                points in the program.  This may be valid e.g., in library 
                                aspects or code picking up error conditions, but often the
                                programmer simply made a mistake in the pointcut.  The best
                                approach is to debug the pointcut.
                            </td></tr><tr><td><tt>invalidAbsoluteTypeName</tt></td><td><tt>warning</tt></td><td>
                            	Issued when an exact type in a pointcut does not match any type
                                in the system.  Note that this can interact with the rules for
                                resolving simple types, which permit unqualified names if they
                                are imported.
                            </td></tr><tr><td><tt>typeNotExposedToWeaver</tt></td><td><tt>warning</tt></td><td>
                            	This means that a type which could be affected by an aspect
                                is not available for weaving.  This happens when a class on
                                the classpath should be woven.
                            </td></tr><tr><td><tt>runtimeExceptionNotSoftened</tt></td><td><tt>warning</tt></td><td>
                            	Before AspectJ 5, declare soft used to soften runtime exceptions
                                (unnecessarily).  Since then, it does not but does issue this 
                                warning in case the programmer did intend for the exception
                                to be wrapped.
                            </td></tr><tr><td><tt>unmatchedSuperTypeInCall</tt></td><td><tt>warning</tt></td><td>
                            	Issued when a call pointcut specifies a defining type which
                                is not matched at the call site (where the declared type of
                                the reference is used, not the actual runtime type).  Most
                                people should use
                                'target(Foo) &amp;&amp; call(void foo())'
                                instead.
                            </td></tr></tbody></table></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="pointcuts"></a>Chapter 2. Debugging Pointcuts</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#pointcuts-introduction">Introduction</a></dt><dt><a href="#pointcuts-debugging">Debugging pointcuts</a></dt></dl></div><div class="sect1"><a name="pointcuts-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="pointcuts-introduction"></a>Introduction</h2></div></div><p> 
        This section describes how to write and debug pointcuts
        using the usual approach of iteration and decomposition.
        New users are often stumped when their advice does not match.
        That means the pointcut doesn't match; they rewrite the
        pointcut and it still doesn't match, with no new information.
        This can be frustrating if each iteration involves building,
        deploying, and testing a complex application.  Learning to
        break it down, particularly into parts that can be checked
        at compile-time, can save a lot of time.
    </p></div><div class="sect1"><a name="pointcuts-debugging"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="pointcuts-debugging"></a>Debugging pointcuts</h2></div></div><p>
Go at it top-down and then bottom-up.  Top-down, draft significant
aspects by first writing the comments to specify responsibilities.
Advice responsibility usually takes the form, "When X, do Y."
Pointcut responsibility for "When X" often takes the form,
"When [join points] [in locations] [are ...]".  These []'s often
translate to named pointcuts (like `libraryCalls() &amp;&amp; within(Client)
&amp;&amp; args(Context)`) which form a semantic bridge to the plain-text
meaning in a comment (e.g., `// when the client passes only context into
the library`).        
This gets you to a point where you can debug the parts of the
pointcut independently.
    </p><p>
Bottom up (to build each part), consider each primitive pointcut
designator (PCD), then the composition, and then any implicit
constraints:
    <div class="orderedlist"><ol type="1"><li><p><a name="d0e358"></a>
What kinds of join points should it match? (constructor-call?
field-get?)?  This translates to using the kinded pointcuts
(`call(..)`, `get(..)`, etc.).
    </p></li><li><p><a name="d0e361"></a>
Are these restricted to being lexically within something?  This
translates to using `within{code}(..)`.  If this is true, it should
always be used, to speed up weaving.
    </p></li><li><p><a name="d0e364"></a>
What runtime constraints and context should be true and available at
each join point?  This translates to `this()`, `target()`, `args()`,
`cflow{below}()` and `if(..)`.
    </p></li><li><p><a name="d0e367"></a>
Are there any advice or implementation limitations at issue?  This
involves knowing the few constraints on AspectJ imposed by Java bytecode 
as listed in the AspectJ Programming Guide section on 
        <a href="../progguide/implementation.html" target="_top">Implementation Notes</a>.
    </p></li></ol></div>
    </p><p>
       It's much faster to iterate a pointcut at compile-time
        using declare warning (even better, some errors are identified
        at parse-time in the latest versions of AJDT).
        Start with the parts of the pointcut
        that are staticly-determinable (i.e., they do not involve
        the runtime PCD's listed above).  If compiles themselves
        take too long because of all the AspectJ weaving, then
        try to only include the debugging aspect with the prototype
        pointcut, and limit the scope using <tt>within(..)</tt>.
    </p><p>
        Some mistakes in primitive pointcuts:
        <div class="itemizedlist"><ul><li><p><a name="d0e382"></a>
`this(Foo) &amp;&amp; execution(static * *(..))`: There is no `this` in a static
context, so `this()` or `target()` should not be used in a static
context or when targetting a static context (respectively).  This
happens most often when you want to say things like "all calls to Foo from Bar"
and you only pick out calls to instance methods of Foo
or you try to pick out calls from static methods of Bar.
</p></li><li><p><a name="d0e385"></a>
`target(Foo) &amp;&amp;  call(new(..)`: This will never match.  In
constructor-call join points, there is no target because the object
has not been created yet. 
</p></li><li><p><a name="d0e388"></a>
`call(* Foo.*(..))`: `Foo` refers to the compile-time type of the
invoking reference, not the implementing class.  In Java before 1.4,
the compile-time type was rendered as the defining type, not the
reference type; this was corrected in 1.4 (as shown when using ajc
with the -1.4 flag)  Most people should use `target(Foo) &amp;&amp;  call(...)`.
</p></li><li><p><a name="d0e391"></a>
`execution(* Foo.bar(..))`: An execution join point for Foo is
always within Foo, so this won't pick out any overrides of bar(..).
Use `target(Foo) &amp;&amp;  execution(* bar(..))` for instance methods.
</p></li><li><p><a name="d0e394"></a>
`within(Foo)`: anonymous types are not known at weave-time to be
within the lexically-enclosing type (a limitation of Java bytecode).
</p></li></ul></div>
    </p><p>
        Some mistakes in composition:
        <div class="itemizedlist"><ul><li><p><a name="d0e401"></a>
`call(* foo(Bar, Foo)) &amp;&amp; args(Foo)`: This will never match.
The parameters in `args(..)` are position-dependent, so `args(Foo)` only picks
 out join points where there is only one argument possible, of type Foo.
Use the indeterminate-arguments operator '..' as needed, e.g., `args(Foo, ..)`.
</p></li><li><p><a name="d0e404"></a>
`call(* foo()) &amp;&amp; execution(* foo())`: This will never match.  Each
pointcut must be true at each join point matched.  For a union of different
kinds of join points (here, call or execution), use '||'.
E.g., to match both method-call and field-get join points, use 
    `call(* ...) || get(...)`.
</p></li></ul></div>
    </p><p>
        Some mistakes in implicit advice constraints:
        <div class="itemizedlist"><ul><li><p><a name="d0e411"></a>
`after () returning (Foo foo) : ...`: after advice can bind the
returned object or exception thrown.  That effectively acts like
`target()`, `this()`, or `args()` in restricting when the advice
runs based on the runtime type of the bound object, even though it is
not explicitly part of the pointcut.
</p></li></ul></div>
    </p><p>
        Some mistakes in implementation requirements:
        <div class="itemizedlist"><ul><li><p><a name="d0e418"></a>
`ajc` has to control the code for a join point in order to implement
the join point.  This translates to an implicit `within({code under
the control of the compiler})` for all join points, with additional
caveat for some join points.  Take exception handlers, for example:
there is no way to be sure from the bytecode where the original handler
ends, so `ajc` can't implement after advice on handler join points.
(Since these are on a per-join-point basis, they should be considered
for each corresponding primitive pointcut designator.)  Unlike the
mistakes with the primitive PCDs above, the compiler will emit an
error for these caveats.
</p></li><li><p><a name="d0e421"></a>
`call(@SuperAnnotation Subclass.meth()`: Annotations are not inherited
by default, so e.g., if the pointcut specifies an annotation, then 
subclass implementations of that method will not be matched.
</p></li></ul></div>
    </p></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="ajcore"></a>Chapter 3. AspectJ Core Files</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#ajcore-introduction">Introduction</a></dt><dd><dl><dt><a href="#configuration">Configuring dump files</a></dt><dt><a href="#ajcore-examples">AJCore File Examples</a></dt></dl></dd></dl></div><div class="sect1"><a name="ajcore-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="ajcore-introduction"></a>Introduction</h2></div></div><p> When the compiler terminates abnormally, either because a particular kind of message was
        issued or an exception was thrown, an AspectJ core file will be produced. You will
        find it the working directory of the compiler and it will have a name that contains
        the date and time that the file was produced 
        e.g. <tt>ajcore.20060810.173655.626.txt</tt>. The file contains details
        of the problem such as the exception thrown as well as information about the
        environment such as operating system and Java version. When submitting a bug,
        include this file whenever it is available.</p><div class="sect2"><a name="configuration"></a><div class="titlepage"><div><h3 class="title"><a name="configuration"></a>Configuring dump files</h3></div></div><p> By default AspectJ will only create an <tt>ajcore</tt> file 
            when an unexpected exception is thrown by the weaver or an 
            <tt>abort</tt> message is
            issued. However it is possible to disable this feature or enable files to
            be produced under different circumstances. The table below lists the System 
            properties that can be used to configure <tt>ajcore</tt> files. </p><div class="informaltable" id="d0e450"><a name="d0e450"></a><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Property</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><tt>org.aspectj.weaver.Dump.exception</tt></td><td><tt>true</tt></td><td>
                            	Generate an <tt>ajcore</tt> files when an exception thrown.
                            </td></tr><tr><td><tt>org.aspectj.weaver.Dump.condition</tt></td><td><tt>abort</tt></td><td>
                            	Message kind for which to generate <tt>ajcore</tt>
                            	e.g. <tt>error</tt>. 
                            </td></tr><tr><td><tt>org.aspectj.dump.directory</tt></td><td><tt>none</tt></td><td>
                            	The directory used for ajcore files. 
                            </td></tr></tbody></table></div></div><div class="sect2"><a name="ajcore-examples"></a><div class="titlepage"><div><h3 class="title"><a name="ajcore-examples"></a>AJCore File Examples</h3></div></div><p> Below is an extract from an <tt>ajcore</tt> file. You will see
            details of the dump configuration as well as the exception (with stack trace) that
            is the source of the problem and any messages issued by the compiler. Most importantly
            the exact version of AspectJ is included. </p><pre class="programlisting">
---- AspectJ Properties ---
AspectJ Compiler DEVELOPMENT built on Tuesday Jul 25, 2006 at 13:00:09 GMT
---- Dump Properties ---
Dump file: ajcore.20060810.173655.626.txt
Dump reason: java.lang.NoClassDefFoundError
Dump on exception: true
Dump at exit condition: abort
---- Exception Information ---
java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory
	at org.aspectj.weaver.tools.CommonsTraceFactory.&lt;init&gt;(CommonsTraceFactory.java:17)
	at java.lang.Class.newInstance0(Native Method)
	at java.lang.Class.newInstance(Class.java:232)
	at org.aspectj.weaver.tools.TraceFactory.&lt;clinit&gt;(TraceFactory.java:35)
	at org.aspectj.weaver.World.&lt;clinit&gt;(World.java:114)
	at org.aspectj.ajdt.internal.core.builder.AjBuildManager.initBcelWorld(AjBuildManager.java:679)
	at org.aspectj.ajdt.internal.core.builder.AjBuildManager.doBuild(AjBuildManager.java:224)
	at org.aspectj.ajdt.internal.core.builder.AjBuildManager.batchBuild(AjBuildManager.java:164)
	at org.aspectj.ajdt.ajc.AjdtCommand.doCommand(AjdtCommand.java:112)
	at org.aspectj.ajdt.ajc.AjdtCommand.runCommand(AjdtCommand.java:60)
	at org.aspectj.tools.ajc.Main.run(Main.java:367)
	at org.aspectj.tools.ajc.Main.runMain(Main.java:246)
	at org.aspectj.tools.ajc.Main.main(Main.java:86)
---- System Properties ---
java.runtime.name=Java(TM) 2 Runtime Environment, Standard Edition
sun.boot.library.path=C:\jdk1.3.1_16\jre\bin
java.vm.version=1.3.1_16-b06
java.vm.vendor=Sun Microsystems Inc.
java.vendor.url=http://java.sun.com/
path.separator=;
java.vm.name=Java HotSpot(TM) Client VM
file.encoding.pkg=sun.io
java.vm.specification.name=Java Virtual Machine Specification
user.dir=C:\workspaces\org.aspectj\org.aspectj.ant.tests
java.runtime.version=1.3.1_16-b06
java.awt.graphicsenv=sun.awt.Win32GraphicsEnvironment
os.arch=x86
java.io.tmpdir=C:\DOCUME~1\IBM_user\LOCALS~1\Temp\
line.separator=

java.vm.specification.vendor=Sun Microsystems Inc.
java.awt.fonts=
os.name=Windows XP
java.library.path=C:\jdk1.3.1_16\jre\bin;...
java.specification.name=Java Platform API Specification
java.class.version=47.0
os.version=5.1
user.home=C:\Documents and Settings\IBM_user
user.timezone=Europe/London
java.awt.printerjob=sun.awt.windows.WPrinterJob
file.encoding=Cp1252
java.specification.version=1.3
java.class.path=C:\workspaces\org.aspectj\aj-build\dist\tools\lib\aspectjtools.jar
user.name=IBM_user
java.vm.specification.version=1.0
java.home=C:\jdk1.3.1_16\jre
user.language=en
java.specification.vendor=Sun Microsystems Inc.
awt.toolkit=sun.awt.windows.WToolkit
java.vm.info=mixed mode
java.version=1.3.1_16
java.ext.dirs=C:\jdk1.3.1_16\jre\lib\ext
sun.boot.class.path=C:\jdk1.3.1_16\jre\lib\rt.jar;...
java.vendor=Sun Microsystems Inc.
file.separator=\
java.vendor.url.bug=http://java.sun.com/cgi-bin/bugreport.cgi
sun.io.unicode.encoding=UnicodeLittle
sun.cpu.endian=little
user.region=GB
sun.cpu.isalist=pentium i486 i386
---- Command Line ---
-d
C:\workspaces\org.aspectj\org.aspectj.ant.tests\IncrementalAjcTaskTest-temp
-g:none
-deprecation
-noExit
-warn:-unusedImport
-nowarn
-XterminateAfterCompilation
-preserveAllLocals
-proceedOnError
-referenceInfo
-source
1.3
-target
1.1
-time
-verbose
-classpath
C:\workspaces\org.aspectj\org.aspectj.ant.tests\..\lib\test\aspectjrt.jar
-argfile
C:\workspaces\org.aspectj\taskdefs\testdata\default.lst
-messageHolder
org.aspectj.bridge.MessageHandler
---- Full Classpath ---
Empty
---- Compiler Messages ---
abort ABORT -- (NoClassDefFoundError) org/apache/commons/logging/LogFactory
org/apache/commons/logging/LogFactory
java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory
	at org.aspectj.weaver.tools.CommonsTraceFactory.&lt;init&gt;(CommonsTraceFactory.java:17)
	at java.lang.Class.newInstance0(Native Method)
	at java.lang.Class.newInstance(Class.java:232)
	at org.aspectj.weaver.tools.TraceFactory.&lt;clinit&gt;(TraceFactory.java:35)
	at org.aspectj.weaver.World.&lt;clinit&gt;(World.java:114)
	at org.aspectj.ajdt.internal.core.builder.AjBuildManager.initBcelWorld(AjBuildManager.java:679)
	at org.aspectj.ajdt.internal.core.builder.AjBuildManager.doBuild(AjBuildManager.java:224)
	at org.aspectj.ajdt.internal.core.builder.AjBuildManager.batchBuild(AjBuildManager.java:164)
	at org.aspectj.ajdt.ajc.AjdtCommand.doCommand(AjdtCommand.java:112)
	at org.aspectj.ajdt.ajc.AjdtCommand.runCommand(AjdtCommand.java:60)
	at org.aspectj.tools.ajc.Main.run(Main.java:367)
	at org.aspectj.tools.ajc.Main.runMain(Main.java:246)
	at org.aspectj.tools.ajc.Main.main(Main.java:86)
			</pre></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="trace"></a>Chapter 4. Tracing</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#trace-introduction">Introduction</a></dt><dd><dl><dt><a href="#trace-configuration">Configuring Tracing</a></dt><dt><a href="#trace-examples">Examples</a></dt></dl></dd></dl></div><div class="sect1"><a name="trace-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="trace-introduction"></a>Introduction</h2></div></div><p> 
            The AspectJ developers have instrumented the compiler/weaver with
            many "trace" messages for their own debugging use.  These remain in
            the production releases because tracing helps when it is hard to 
            isolate the problem in a test case.  This sections describes how
            to enable tracing so you can provide trace information on bug reports.
        </p><p> 
            The usual approach to opening a report on Bugzilla is to describe the symptoms of the 
        problem and attach a simple testcase. This allows the AspectJ team to try and reproduce the problem in
        an attempt to fix it as well as improve the test suite. Unfortunately it may not be possible
        to produce such a testcase either because your program is too large or is commercially sensitive. Alternatively 
        the problem may relate to your specific environment where AspectJ is being used and will not be
        reproducible by the AspectJ team. In each of these situations you can produce a
        trace of the compiler when the problem occurs instead. This can then be attached to the bug report. </p><div class="sect2"><a name="trace-configuration"></a><div class="titlepage"><div><h3 class="title"><a name="trace-configuration"></a>Configuring Tracing</h3></div></div><p> When available (Java 5 or later) AspectJ will use the 
            <a href="http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html" target="_top">
            java.util.logging</a> infrastructure
            configured using a <tt>logging.properties</tt> file. By default only error
            and fatal events will be logged but less severe warnings as well as fine-grained
            method entry and exit events can be obtained using the appropriate configuration. All
            regular compiler messages can also be logged through the infrastructure by setting the
            <tt>org.aspectj.weaving.messages</tt> System property. </p><p> If you are running the AspectJ compiler/weaver under JDK 1.4 or earlier, 
                AspectJ will use a simple built-in trace
            infrastructure that logs to stderr. This is enabled by setting the 
            <tt>org.aspectj.weaving.tracing.enabled</tt> System property. You may also override
            the default behaviour or provide your own trace implementation using the
            <tt>org.aspectj.weaving.tracing.factory</tt> System property. </p><p> The table below lists the System properties that can be used to configure tracing. </p><div class="informaltable" id="d0e541"><a name="d0e541"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td><tt>org.aspectj.tracing.debug</tt></td><td>
                            	Enable simple debugging of the trace infrastructure itself.
                            	<p> Default: <tt>false</tt>. </p></td></tr><tr><td><tt>org.aspectj.tracing.enabled</tt></td><td>
                            	Enable the built-in AspectJ trace infrastructure.
                            	<p> Default: <tt>false</tt>. </p></td></tr><tr><td><tt>org.aspectj.tracing.factory</tt></td><td>
                            	Select trace infrastructure. Specify the fully qualified class name
                            	of the <tt>org.aspectj.weaver.tools.TraceFactory</tt> 
                            	interface to use a custom infrastructure. Specify a value of
                            	<tt>default</tt> to force AspectJ to use it's
                            	built-in infrastructure. 
                            </td></tr><tr><td><tt>org.aspectj.tracing.messages</tt></td><td>
                            	Enable tracing of compiler messages. The kind of messages logged
                            	is determined by the selected trace infrastructure not the message
                            	configuration.
                            	<p> Default: <tt>false</tt>. </p></td></tr></tbody></table></div></div><div class="sect2"><a name="trace-examples"></a><div class="titlepage"><div><h3 class="title"><a name="trace-examples"></a>Examples</h3></div></div><p> Using <tt>-Dorg.aspectj.tracing.factory=default</tt>
            	to force AspectJ to use its internal infrastructure,
            	<tt>-Dorg.aspectj.tracing.enabled=true</tt> to turn it on and  
            	<tt>-Dorg.aspectj.tracing.messages=true</tt> to include messages
            	running a simple HelloWorld with LTW will generate tracing to stderr. Below
            	is an extract from that trace with method arguments removed. 
            	You will notice the millisecond time stamp,
            	thread id and indication of entry/exit/event or message type for each line
            	of trace.
            </p><pre class="programlisting">
15:44:18.630 main &gt; org.aspectj.weaver.loadtime.Aj.&lt;init&gt; 
15:44:18.660 main &lt; org.aspectj.weaver.loadtime.Aj.&lt;init&gt;
15:44:18.660 main &gt; org.aspectj.weaver.loadtime.Aj.preProcess
15:44:18.660 main - org.aspectj.weaver.loadtime.Aj.preProcess
15:44:18.730 main &gt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.&lt;init&gt;
15:44:18.730 main &lt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.&lt;init&gt;
15:44:18.730 main &gt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.initialize 
15:44:18.821 main I [AppClassLoader@92e78c] info AspectJ Weaver Version DEVELOPMENT ...
15:44:18.821 main &gt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions
15:44:18.821 main I [AppClassLoader@92e78c] info register classloader ...
15:44:18.821 main - org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions 
15:44:18.841 main - org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions 
15:44:18.841 main I [AppClassLoader@92e78c] info using configuration ...
15:44:18.891 main &lt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions 
15:44:19.021 main &gt; org.aspectj.weaver.World$TypeMap.&lt;init&gt;
15:44:19.021 main &lt; org.aspectj.weaver.World$TypeMap.&lt;init&gt;
15:44:19.021 main &gt; org.aspectj.weaver.CrosscuttingMembersSet.&lt;init&gt;
15:44:19.021 main &lt; org.aspectj.weaver.CrosscuttingMembersSet.&lt;init&gt;
15:44:19.021 main &gt; org.aspectj.weaver.Lint.&lt;init&gt;
15:44:19.021 main &lt; org.aspectj.weaver.Lint.&lt;init&gt;
15:44:19.021 main &gt; org.aspectj.weaver.World.&lt;init&gt; 
15:44:19.111 main &lt; org.aspectj.weaver.World.&lt;init&gt;
15:44:19.201 main &gt; org.aspectj.weaver.bcel.BcelWeaver.&lt;init&gt; 
15:44:19.201 main &lt; org.aspectj.weaver.bcel.BcelWeaver.&lt;init&gt;
15:44:19.201 main &gt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerDefinitions 
15:44:19.211 main &gt; org.aspectj.weaver.bcel.BcelWeaver.setReweavableMode 
15:44:19.351 main &lt; org.aspectj.weaver.bcel.BcelWeaver.setReweavableMode
15:44:19.351 main &gt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerAspects 
15:44:19.351 main I [AppClassLoader@92e78c] info register aspect Aspect
15:44:19.351 main &gt; org.aspectj.weaver.bcel.BcelWeaver.addLibraryAspect 
15:44:19.501 main - org.aspectj.weaver.bcel.BcelWorld.lookupJavaClass 
15:44:19.632 main &gt; org.aspectj.weaver.CrosscuttingMembersSet.addOrReplaceAspect 
15:44:19.792 main &lt; org.aspectj.weaver.CrosscuttingMembersSet.addOrReplaceAspect 
15:44:19.792 main &lt; org.aspectj.weaver.bcel.BcelWeaver.addLibraryAspect 
15:44:19.792 main &lt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerAspects 
15:44:19.792 main &lt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerDefinitions 
15:44:19.792 main &gt; org.aspectj.weaver.bcel.BcelWeaver.prepareForWeave 
15:44:19.822 main &lt; org.aspectj.weaver.bcel.BcelWeaver.prepareForWeave
15:44:19.822 main &gt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.weaveAndDefineConcete...
15:44:19.822 main &lt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.weaveAndDefineConcete...
15:44:19.822 main &lt; org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.initialize 
15:44:19.822 main &gt; org.aspectj.weaver.tools.WeavingAdaptor.weaveClass 
...            
			</pre><p> Alternatively when running under Java 5 the <tt>logging.properties</tt>
            	file below could be used to configure Java Logging. The resulting
            	file, just containing trace for the 
            	<tt>org.aspectj.weaver.loadtime</tt> package, will be
            	written to <tt>java0.log</tt> in your <tt>user.home</tt> directory. 
            </p><pre class="programlisting">
handlers= java.util.logging.FileHandler

.level= INFO

java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level = FINER

org.aspectj.weaver.loadtime.level = FINER
			</pre><p> 
            	By setting the System property <tt>-Dorg.aspectj.tracing.debug=true</tt>
            	you should see a message confirming which trace infrastructure is being used.
            </p><pre class="programlisting">
	TraceFactory.instance=org.aspectj.weaver.tools.Jdk14TraceFactory@12dacd1	        
			</pre></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="ltwdump"></a>Chapter 5. Dumping classes during load-time weaving</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#ltwdump-introduction">Introduction</a></dt><dd><dl><dt><a href="#ltw-examples">Configuring bytecode dumping in load-time weaving</a></dt><dt><a href="#ltwdump-examples">LTW Dump Examples</a></dt></dl></dd></dl></div><div class="sect1"><a name="ltwdump-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="ltwdump-introduction"></a>Introduction</h2></div></div><p> 
        	Very rarely problems may be encountered with classes that have been 
        	load-time woven.
        	Symptoms will include incorrect program function or a Java exception such as 
        	<tt>java.lang.VerifyError</tt>.
            In these situations it's most helpful to include the offending class 
            in the bug report. When using load-time weaving the woven classes are 
            in memory only so to save them to disk configure
            <tt>META-INF/aop.xml</tt> to dump the classes (by default 
            to an <tt>_ajdump</tt> subdirectory of the current working 
            directory).  Also if the input class file is not available 
            (e.g. it is a generated proxy or has already been instrumented by another agent)
            you can configure the weaver to dump the input classes as well.
        </p><div class="sect2"><a name="ltw-examples"></a><div class="titlepage"><div><h3 class="title"><a name="ltw-examples"></a>Configuring bytecode dumping in load-time weaving</h3></div></div><p>
  			For details of how to configure byte-code dumping, see the             
            AspectJ Development Environment Guide section on 
				<a href="../devguide/ltw-configuration.html#configuring-load-time-weaving-with-aopxml-files" target="_top">
				Configuring Load-time Weaving</a>.  
            Following is a simple example.
            </p></div><div class="sect2"><a name="ltwdump-examples"></a><div class="titlepage"><div><h3 class="title"><a name="ltwdump-examples"></a>LTW Dump Examples</h3></div></div><p> The following <tt>META-INF/aop.xml</tt> will 
            weave classes in the <tt>com.foo</tt> package (and subpackages) but not
            CGLIB generated classes in the <tt>com.foo.bar</tt> package (and subpackages). 
            It will also ensure all
            woven byte-code is dumped both before and after weaving. </p><pre class="programlisting">
	&lt;aspectj&gt;
		&lt;aspects&gt;
			&lt;aspect name="ataspectj.EmptyAspect"/&gt;
		&lt;/aspects&gt;
	    &lt;weaver options="-verbose -debug"&gt;
	        &lt;dump within="com.foo.bar..*" beforeandafter="true"/&gt; 
    	    &lt;include within="com.foo..*"/&gt;
        	&lt;exclude within="com.foo.bar..*CGLIB*"/&gt;
		&lt;/weaver&gt;
	&lt;/aspectj&gt;
			</pre><p> You should see messages similar to this: </p><pre class="programlisting">
[WeavingURLClassLoader] info AspectJ Weaver Version 1.5.3 built on Thursday Oct 26, 2006 at 17:22:31 GMT
[WeavingURLClassLoader] info register classloader org.aspectj.weaver.loadtime.WeavingURLClassLoader
[WeavingURLClassLoader] info using configuration /C:/tempMETA-INF/aop.xml
[WeavingURLClassLoader] info register aspect ataspectj.EmptyAspect
[WeavingURLClassLoader] debug not weaving 'com.foo.bar.Test$$EnhancerByCGLIB$$12345'
[WeavingURLClassLoader] debug weaving 'com.foo.bar.Test'
			</pre><p> On disk you would find the following files: </p><pre class="programlisting">
	_ajdump/_before/com/foo/bar/Test.class
	_ajdump/com/foo/bar/Test.class
			</pre></div></div></div></div></body></html>